
<!DOCTYPE html>

<html>
  
<!-- Mirrored from docs.sympy.org/latest/modules/matrices/sparsetools.html by HTTrack Website Copier/3.x [XR&CO'2014], Sat, 15 Jan 2022 03:27:05 GMT -->
<!-- Added by HTTrack --><meta http-equiv="content-type" content="text/html;charset=utf-8" /><!-- /Added by HTTrack -->
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />

    <title>Sparse Tools &#8212; SymPy 1.9 documentation</title>
    <link rel="stylesheet" type="text/css" href="../../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../../_static/default.css" />
    <link rel="stylesheet" type="text/css" href="../../_static/graphviz.css" />
    <link rel="stylesheet" type="text/css" href="../../_static/plot_directive.css" />
    <link rel="stylesheet" type="text/css" href="../../../../live.sympy.org/static/live-core.css" />
    <link rel="stylesheet" type="text/css" href="../../../../live.sympy.org/static/live-autocomplete.css" />
    <link rel="stylesheet" type="text/css" href="../../../../live.sympy.org/static/live-sphinx.css" />
    
    <script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script>
    <script src="../../_static/jquery.js"></script>
    <script src="../../_static/underscore.js"></script>
    <script src="../../_static/doctools.js"></script>
    <script src="../../../../live.sympy.org/static/utilities.js"></script>
    <script src="../../../../live.sympy.org/static/external/classy.js"></script>
    <script src="../../../../live.sympy.org/static/live-core.js"></script>
    <script src="../../../../live.sympy.org/static/live-autocomplete.js"></script>
    <script src="../../../../live.sympy.org/static/live-sphinx.js"></script>
    
    <link rel="shortcut icon" href="../../_static/sympy-notailtext-favicon.ico"/>
    <link href="sparsetools.html" rel="canonical" />
    
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" />
    <link rel="next" title="Immutable Matrices" href="immutablematrices.html" />
    <link rel="prev" title="Sparse Matrices" href="sparse.html" /> 
  </head><body>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../../genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="../../py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="immutablematrices.html" title="Immutable Matrices"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="sparse.html" title="Sparse Matrices"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="../../index.html">SymPy 1.9 documentation</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="../index.html" >SymPy Modules Reference</a> &#187;</li>
          <li class="nav-item nav-item-2"><a href="index.html" accesskey="U">Matrices</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="#">Sparse Tools</a></li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="module-sympy.matrices.sparsetools">
<span id="sparse-tools"></span><span id="matrices-sparsetools"></span><h1>Sparse Tools<a class="headerlink" href="#module-sympy.matrices.sparsetools" title="Permalink to this headline">¶</a></h1>
<dl class="py method">
<dt class="sig sig-object py" id="sympy.matrices.sparsetools._doktocsr">
<span class="sig-prename descclassname"><span class="pre">sympy.matrices.sparsetools.</span></span><span class="sig-name descname"><span class="pre">_doktocsr</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference external" href="https://github.com/sympy/sympy/blob/00d6469eafdd4aac346a0b598184c15f2560dbe5/sympy/matrices/sparsetools.py#L8-L38"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#sympy.matrices.sparsetools._doktocsr" title="Permalink to this definition">¶</a></dt>
<dd><p>Converts a sparse matrix to Compressed Sparse Row (CSR) format.</p>
<dl class="field-list">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>A</strong> : contains non-zero elements sorted by key (row, column)</p>
<p><strong>JA</strong> : JA[i] is the column corresponding to A[i]</p>
<p><strong>IA</strong> : IA[i] contains the index in A for the first non-zero element</p>
<blockquote>
<div><p>of row[i]. Thus IA[i+1] - IA[i] gives number of non-zero
elements row[i]. The length of IA is always 1 more than the
number of rows in the matrix.</p>
</div></blockquote>
</dd>
</dl>
<p class="rubric">Examples</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">sympy.matrices.sparsetools</span> <span class="kn">import</span> <span class="n">_doktocsr</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">sympy</span> <span class="kn">import</span> <span class="n">SparseMatrix</span><span class="p">,</span> <span class="n">diag</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">m</span> <span class="o">=</span> <span class="n">SparseMatrix</span><span class="p">(</span><span class="n">diag</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="p">[</span><span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">]</span> <span class="o">=</span> <span class="o">-</span><span class="mi">1</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">_doktocsr</span><span class="p">(</span><span class="n">m</span><span class="p">)</span>
<span class="go">[[1, 2, -1, 3], [0, 1, 0, 2], [0, 1, 2, 4], [3, 3]]</span>
</pre></div>
</div>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="sympy.matrices.sparsetools._csrtodok">
<span class="sig-prename descclassname"><span class="pre">sympy.matrices.sparsetools.</span></span><span class="sig-name descname"><span class="pre">_csrtodok</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference external" href="https://github.com/sympy/sympy/blob/00d6469eafdd4aac346a0b598184c15f2560dbe5/sympy/matrices/sparsetools.py#L41-L62"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#sympy.matrices.sparsetools._csrtodok" title="Permalink to this definition">¶</a></dt>
<dd><p>Converts a CSR representation to DOK representation.</p>
<p class="rubric">Examples</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">sympy.matrices.sparsetools</span> <span class="kn">import</span> <span class="n">_csrtodok</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">_csrtodok</span><span class="p">([[</span><span class="mi">5</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">6</span><span class="p">],</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">],</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">],</span> <span class="p">[</span><span class="mi">4</span><span class="p">,</span> <span class="mi">3</span><span class="p">]])</span>
<span class="go">Matrix([</span>
<span class="go">[0, 0, 0],</span>
<span class="go">[5, 8, 0],</span>
<span class="go">[0, 0, 3],</span>
<span class="go">[0, 6, 0]])</span>
</pre></div>
</div>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="sympy.matrices.sparsetools.banded">
<span class="sig-prename descclassname"><span class="pre">sympy.matrices.sparsetools.</span></span><span class="sig-name descname"><span class="pre">banded</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/sympy/sympy/blob/00d6469eafdd4aac346a0b598184c15f2560dbe5/sympy/matrices/sparsetools.py#L65-L300"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#sympy.matrices.sparsetools.banded" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a SparseMatrix from the given dictionary describing
the diagonals of the matrix. The keys are positive for upper
diagonals and negative for those below the main diagonal. The
values may be:</p>
<ul class="simple">
<li><p>expressions or single-argument functions,</p></li>
<li><p>lists or tuples of values,</p></li>
<li><p>matrices</p></li>
</ul>
<p>Unless dimensions are given, the size of the returned matrix will
be large enough to contain the largest non-zero value provided.</p>
<p class="rubric">Kwargs</p>
<dl class="simple">
<dt>rows<span class="classifier">rows of the resulting matrix; computed if</span></dt><dd><p>not given.</p>
</dd>
<dt>cols<span class="classifier">columns of the resulting matrix; computed if</span></dt><dd><p>not given.</p>
</dd>
</dl>
<p class="rubric">Examples</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">sympy</span> <span class="kn">import</span> <span class="n">banded</span><span class="p">,</span> <span class="n">ones</span><span class="p">,</span> <span class="n">Matrix</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">sympy.abc</span> <span class="kn">import</span> <span class="n">x</span>
</pre></div>
</div>
<p>If explicit values are given in tuples,
the matrix will autosize to contain all values, otherwise
a single value is filled onto the entire diagonal:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">banded</span><span class="p">({</span><span class="mi">1</span><span class="p">:</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">),</span> <span class="o">-</span><span class="mi">1</span><span class="p">:</span> <span class="p">(</span><span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">),</span> <span class="mi">0</span><span class="p">:</span> <span class="n">x</span><span class="p">})</span>
<span class="go">Matrix([</span>
<span class="go">[x, 1, 0, 0],</span>
<span class="go">[4, x, 2, 0],</span>
<span class="go">[0, 5, x, 3],</span>
<span class="go">[0, 0, 6, x]])</span>
</pre></div>
</div>
<p>A function accepting a single argument can be used to fill the
diagonal as a function of diagonal index (which starts at 0).
The size (or shape) of the matrix must be given to obtain more
than a 1x1 matrix:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">s</span> <span class="o">=</span> <span class="k">lambda</span> <span class="n">d</span><span class="p">:</span> <span class="p">(</span><span class="mi">1</span> <span class="o">+</span> <span class="n">d</span><span class="p">)</span><span class="o">**</span><span class="mi">2</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">banded</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="p">{</span><span class="mi">0</span><span class="p">:</span> <span class="n">s</span><span class="p">,</span> <span class="mi">2</span><span class="p">:</span> <span class="n">s</span><span class="p">,</span> <span class="o">-</span><span class="mi">2</span><span class="p">:</span> <span class="mi">2</span><span class="p">})</span>
<span class="go">Matrix([</span>
<span class="go">[1, 0, 1,  0,  0],</span>
<span class="go">[0, 4, 0,  4,  0],</span>
<span class="go">[2, 0, 9,  0,  9],</span>
<span class="go">[0, 2, 0, 16,  0],</span>
<span class="go">[0, 0, 2,  0, 25]])</span>
</pre></div>
</div>
<p>The diagonal of matrices placed on a diagonal will coincide
with the indicated diagonal:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">vert</span> <span class="o">=</span> <span class="n">Matrix</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">banded</span><span class="p">({</span><span class="mi">0</span><span class="p">:</span> <span class="n">vert</span><span class="p">},</span> <span class="n">cols</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>
<span class="go">Matrix([</span>
<span class="go">[1, 0, 0],</span>
<span class="go">[2, 1, 0],</span>
<span class="go">[3, 2, 1],</span>
<span class="go">[0, 3, 2],</span>
<span class="go">[0, 0, 3]])</span>
</pre></div>
</div>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">banded</span><span class="p">(</span><span class="mi">4</span><span class="p">,</span> <span class="p">{</span><span class="mi">0</span><span class="p">:</span> <span class="n">ones</span><span class="p">(</span><span class="mi">2</span><span class="p">)})</span>
<span class="go">Matrix([</span>
<span class="go">[1, 1, 0, 0],</span>
<span class="go">[1, 1, 0, 0],</span>
<span class="go">[0, 0, 1, 1],</span>
<span class="go">[0, 0, 1, 1]])</span>
</pre></div>
</div>
<p>Errors are raised if the designated size will not hold
all values an integral number of times. Here, the rows
are designated as odd (but an even number is required to
hold the off-diagonal 2x2 ones):</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">banded</span><span class="p">({</span><span class="mi">0</span><span class="p">:</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">:</span> <span class="n">ones</span><span class="p">(</span><span class="mi">2</span><span class="p">)},</span> <span class="n">rows</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">ValueError</span>:
<span class="go">sequence does not fit an integral number of times in the matrix</span>
</pre></div>
</div>
<p>And here, an even number of rows is given…but the square
matrix has an even number of columns, too. As we saw
in the previous example, an odd number is required:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">banded</span><span class="p">(</span><span class="mi">4</span><span class="p">,</span> <span class="p">{</span><span class="mi">0</span><span class="p">:</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">:</span> <span class="n">ones</span><span class="p">(</span><span class="mi">2</span><span class="p">)})</span>  <span class="c1"># trying to make 4x4 and cols must be odd</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">ValueError</span>:
<span class="go">sequence does not fit an integral number of times in the matrix</span>
</pre></div>
</div>
<p>A way around having to count rows is to enclosing matrix elements
in a tuple and indicate the desired number of them to the right:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">banded</span><span class="p">({</span><span class="mi">0</span><span class="p">:</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">:</span> <span class="p">(</span><span class="n">ones</span><span class="p">(</span><span class="mi">2</span><span class="p">),)</span><span class="o">*</span><span class="mi">3</span><span class="p">})</span>
<span class="go">Matrix([</span>
<span class="go">[2, 0, 1, 1, 0, 0, 0, 0],</span>
<span class="go">[0, 2, 1, 1, 0, 0, 0, 0],</span>
<span class="go">[0, 0, 2, 0, 1, 1, 0, 0],</span>
<span class="go">[0, 0, 0, 2, 1, 1, 0, 0],</span>
<span class="go">[0, 0, 0, 0, 2, 0, 1, 1],</span>
<span class="go">[0, 0, 0, 0, 0, 2, 1, 1]])</span>
</pre></div>
</div>
<p>An error will be raised if more than one value
is written to a given entry. Here, the ones overlap
with the main diagonal if they are placed on the
first diagonal:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">banded</span><span class="p">({</span><span class="mi">0</span><span class="p">:</span> <span class="p">(</span><span class="mi">2</span><span class="p">,)</span><span class="o">*</span><span class="mi">5</span><span class="p">,</span> <span class="mi">1</span><span class="p">:</span> <span class="p">(</span><span class="n">ones</span><span class="p">(</span><span class="mi">2</span><span class="p">),)</span><span class="o">*</span><span class="mi">3</span><span class="p">})</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">ValueError</span>: <span class="n">collision at (1, 1)</span>
</pre></div>
</div>
<p>By placing a 0 at the bottom left of the 2x2 matrix of
ones, the collision is avoided:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">u2</span> <span class="o">=</span> <span class="n">Matrix</span><span class="p">([</span>
<span class="gp">... </span><span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">],</span>
<span class="gp">... </span><span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">]])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">banded</span><span class="p">({</span><span class="mi">0</span><span class="p">:</span> <span class="p">[</span><span class="mi">2</span><span class="p">]</span><span class="o">*</span><span class="mi">5</span><span class="p">,</span> <span class="mi">1</span><span class="p">:</span> <span class="p">[</span><span class="n">u2</span><span class="p">]</span><span class="o">*</span><span class="mi">3</span><span class="p">})</span>
<span class="go">Matrix([</span>
<span class="go">[2, 1, 1, 0, 0, 0, 0],</span>
<span class="go">[0, 2, 1, 0, 0, 0, 0],</span>
<span class="go">[0, 0, 2, 1, 1, 0, 0],</span>
<span class="go">[0, 0, 0, 2, 1, 0, 0],</span>
<span class="go">[0, 0, 0, 0, 2, 1, 1],</span>
<span class="go">[0, 0, 0, 0, 0, 0, 1]])</span>
</pre></div>
</div>
</dd></dl>

</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
            <p class="logo"><a href="../../index.html">
              <img class="logo" src="../../_static/sympylogo.png" alt="Logo"/>
            </a></p>
  <h4>Previous topic</h4>
  <p class="topless"><a href="sparse.html"
                        title="previous chapter">Sparse Matrices</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="immutablematrices.html"
                        title="next chapter">Immutable Matrices</a></p>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="../../_sources/modules/matrices/sparsetools.rst.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="https://docs.sympy.org/latest/search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>
    </div>
</div>
<script>$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../../genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="../../py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="immutablematrices.html" title="Immutable Matrices"
             >next</a> |</li>
        <li class="right" >
          <a href="sparse.html" title="Sparse Matrices"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="../../index.html">SymPy 1.9 documentation</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="../index.html" >SymPy Modules Reference</a> &#187;</li>
          <li class="nav-item nav-item-2"><a href="index.html" >Matrices</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="#">Sparse Tools</a></li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
        &#169; Copyright 2021 SymPy Development Team.
      Last updated on Sep 30, 2021.
      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.1.2.
    </div>
  </body>

<!-- Mirrored from docs.sympy.org/latest/modules/matrices/sparsetools.html by HTTrack Website Copier/3.x [XR&CO'2014], Sat, 15 Jan 2022 03:27:05 GMT -->
</html>